home *** CD-ROM | disk | FTP | other *** search
/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / COMMADIO / FREESPCH.LZH / VARITALE.LZH / MANUAL.DOC < prev    next >
Text File  |  1991-06-14  |  18KB  |  662 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                         THE VARITALE AUTHORING SYSTEM
  11.  
  12.                                 Release: C1.01
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                               Operator's Manual
  22.  
  23.                              Summer 1991 Edition
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.                       P I N N A C L E   S O F T W A R E
  32.  
  33.                       P.O. Box 386, Town of Mount Royal
  34.                       Montreal, Quebec, Canada  H3P 3C6
  35.  
  36.                                 (514) 345-9578
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.                                    NOTICES
  80.  
  81. This  publication  could  include  technical  inaccuracies  or  typographical
  82. errors.
  83.  
  84. Changes are periodically made  to the information herein; these  changes will
  85. be incorporated in new editions of this publication.
  86.  
  87. Requests for  copies of this product and  for technical information about the
  88. system should be  made to your authorized  VariTale dealer or to  the address
  89. indicated in the licensing agreement.
  90.  
  91. The VariTale product is Copyright (C) 1987 by Pinnacle Software.
  92.  
  93.  
  94. Upgrades and Support
  95.  
  96. Registered  users of this  product are entitled  to call us  for support, and
  97. will receive news of updates, bug reports, and special discounts for Pinnacle
  98. Software products.
  99.  
  100. This support  arrangement will  remain in  effect for  one year,  and may  be
  101. renewed each year for $10.
  102.  
  103.  
  104. Private Information
  105.  
  106. The information contained in  this manual is intended  only for operators  of
  107. VariTale  installations.   You are requested  to keep  it private.   Under no
  108. circumstances may this manual be copied in any way.
  109.  
  110.  
  111. Dedication
  112.  
  113. (From Timothy Campbell, creator of VariTale)
  114.  
  115. The inspiration  for VariTale  came from  many sources,  but one  significant
  116. influence was  the HyperText system proposed  by computer guru  Ted Nelson in
  117. his book "Computer  Lib/Dream Machines".  If you haven't read  it, you owe it
  118. to yourself to get your hands on a copy.  Whence the sequel, Ted? 
  119.  
  120. Note,  though, that  VariTale is  not  HyperText and  makes no  claim  to be.
  121. Everything is deeply intertwingled, but some things more so than others.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128. ii
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142. NOTICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  ii
  143.      Upgrades and Support
  144.      Private Information
  145.      Dedication
  146.  
  147. WHAT IS VARITALE? . . . . . . . . . . . . . . . . . . . . . . . . . . . .   1
  148.  
  149. INSTALLING VARITALE . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
  150.      What You Need
  151.      Installation Steps
  152.      Getting Things Rolling
  153.  
  154. DOOR OPERATION  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   3
  155.  
  156. MULTI-USER OPERATION  . . . . . . . . . . . . . . . . . . . . . . . . . .   4
  157.      File Locking
  158.      The Unique File-locking Tag
  159.      Single-Processor Operation
  160.      LAN Operation
  161.  
  162. MAINTENANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   6
  163.      Backups
  164.      Librarian Commands
  165.      BURN
  166.      CLOSE
  167.      RENAME
  168.      Why Show the Commands?
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                                                                           iii
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.                               WHAT IS VARITALE?
  208.  
  209. VariTale is a "branching authoring system", designed to run either locally on
  210. your computer screen, or  as a "Door" on  BBS systems such as PCBoard,  RBBS,
  211. NoChange, Fido, ROS, Sapphire and so on.
  212.  
  213. You will be  able to write stories  (known in VariTale as  "books") that have
  214. alternate chapters.  Here is an example of a branching tale:
  215.  
  216.  
  217.         .---------------- I woke up -----------------.
  218.         :                                            :
  219. .------ I went back to sleep ----.              .--- I made breakfast ---.
  220. :                                :              :                        :
  221. I dreamed up a new program   I had no dreams    It was bad     It was good
  222.  
  223.  
  224. At any point, there is always an alternative.   In VariTale, each step (known
  225. in VariTale as  "chapters") can be  up to 50  lines long.   After each  step,
  226. there can be up to 5 alternatives.
  227.  
  228. This allows you and other people to create "story-rounds", in which everybody
  229. contributes chapters to  the tale.   Story-rounds  are quite  popular on  BBS
  230. systems, but there is  a problem:  somebody will take the  story in the wrong
  231. direction,  and the other writers get  annoyed.  And that  is the end of that
  232. story.
  233.  
  234. With VariTale, the writers can propose alternate chapters, either in response
  235. to an  inappropriate effort by  another writer, or  simply to explore  a dif-
  236. ferent facet of the story.
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                                                             1
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.                              INSTALLING VARITALE
  274.  
  275.  
  276. What You Need
  277.  
  278. VariTale is very easy  to install.  It will  run under MS- or PC-DOS  Version
  279. 2.00 and higher, on any 128K IBM-PC or compatible.  
  280.  
  281. VariTale  should be run  on a  hard disk  if you expect  any kind  of serious
  282. traffic  on the  program.   Its  file-handling is  quite  efficient, but  the
  283. chapters can stack up  quite quickly.  Apart from  that, though, there is  no
  284. reason why it cannot be run on floppies.
  285.  
  286.  
  287. Installation Steps
  288.  
  289. To get VariTale running on your system, follow these steps:
  290.  
  291.      1.   Make a backup copy of the original diskette.
  292.  
  293.      2.   Prepare a destination for the VariTale files.
  294.  
  295.           A.   If using a hard disk, this means creating a directory, usually
  296.                named VARITALE.
  297.  
  298.           B.   If using floppies, this means formatting a diskette.
  299.  
  300.      3.   Copy the necessary files from the original diskette to their proper
  301.           place (on a hard disk or a floppy).  Use the DOS COPY command to do
  302.           this.
  303.  
  304.      4.   Configure VariTale to  work according to your wants and needs.  The
  305.           CONFIG program will take you through the necessary steps.
  306.  
  307.      5.   Run a local  test.  The VARITALE  command will do this.   This runs
  308.           the program  locally, with  absolutely no reference  to the  modem.
  309.           You can run VariTale in this manner at any time.
  310.  
  311.      6.   If  you wish to run VariTale  as a Door, refer  to the "Door Opera-
  312.           tion" section of this manual.
  313.  
  314.  
  315. Getting Things Rolling
  316.  
  317. On  some BBS's, VariTale needs  a little push to establish  it as a regularly
  318. used feature of the system.  People are not encouraged to start a story-round
  319. if  they feel they're alone.  You should  get a few budding writers together,
  320. have them work out a rough plot, then start at the same time.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326. 2
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.                                 DOOR OPERATION
  340.  
  341.  
  342. This manual  is not intended to  be a tutorial  for door operations.   Please
  343. consult your host BBS's documentation for full details.
  344.  
  345. In general, you will create a batch  (.BAT) file which will call up VariTale,
  346. using a special  start-up command that  will be explained shortly.   VariTale
  347. handles problems  such as  lost carriers, so  there is  no need  for watchdog
  348. timers and suchlike things.
  349.  
  350. To start up VariTale, place the following command in your door batch file:
  351.  
  352.                    VARITALE /DOOR/user-name/time-left/port 
  353.  
  354. user-name ....... If omitted, none assumed 
  355.                     This is optional.  It is used only in the activity report
  356.                     generated by  the  CLOSE command  if  you are  running  a
  357.                     multi-user system.
  358.  
  359. time-left ....... If omitted, assumes 60 minutes maximum visit time 
  360.  
  361. port ............ Current port address, in decimal
  362.                If omitted, assumes default port from CONFIG.DAT
  363.                If 0, no modem reference (i.e. console) 
  364.                If D, door is forced opened (use after system crash ONLY)    
  365. Here are some examples...
  366.  
  367. VARITALE /DOOR///1016          No name assumed, 60 minutes, on COM1
  368. VARITALE /DOOR//15/0           No name assumed, 15 minutes, console 
  369. VARITALE /DOOR/JOE SMITH/60    For Joe Smith, 1 hour on default port
  370. VARITALE /DOOR///1016          No name, 60 minutes, on COM1 (decimal 1016)
  371. VARITALE /DOOR///A1016         With system ID for LAN use (explained later)
  372.  
  373. Information such  as real-name, time-left  and port  can be  determined by  a
  374. program you write  to build a command line.   On a multi-port  system, such a
  375. program  is  not optional;  you must  pass  information to  be used  for file
  376. locking  purposes.   If are  running a  LAN, you  may have  to pass  a system
  377. identifier letter.  See "Multi-User Operation" for details. 
  378.  
  379. We will be collecting  appropriate command-line builder programs for  various
  380. BBS systems.  See the "Upgrades and Support" section for more information.
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                                                                             3
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.                              MULTI-USER OPERATION
  406.  
  407.  
  408. This section is directed  towards users of multi-port systems.   You can skip
  409. it if you configured VariTale for a single-user system. 
  410.  
  411.  
  412. File Locking
  413.  
  414. "Locking" means claiming exclusive use  of a resource.  In the  case of Vari-
  415. Tale,  for instance, it means that a book can be used only by one person at a
  416. time.
  417.  
  418. VariTale does its own  file locking.  It  does not use the file  locking pro-
  419. vided with  DOS 3 and higher, nor does it  use locking techniques such as the
  420. one provided by MultiLink.   VariTale's locking technique is slower than that
  421. provided by the  aforementioned products.  On  the other hand, it  does allow
  422. you to run VariTale under a wide range of environments. 
  423.  
  424. It's slower  because all locking  information is recorded  in the .LOK  file,
  425. using a "collision detection"  scheme.  This obviously has  lower performance
  426. than  a  RAM-based locking  table, but  it  minimizes interaction  with other
  427. products, thereby maximizing compatibility. 
  428.  
  429. If you are  running a LAN  (Local Area Network),  be careful of  disk-caching
  430. software because  this might prevent  locking information  from reaching  the
  431. locking file properly.   VariTale synchronizes  locking file updates by  per-
  432. forming a dummy write  before checking for collision, but a  cache would make
  433. this approach useless if it withholds disk writes. 
  434.  
  435. There is one major problem with  a disk-based locking table:  if  your system
  436. crashes,  it will  faithfully remember  the  locking data!    This data  will
  437. "time-out"  after an  hour (the  maximum time  allowed in  VariTale), so  the
  438. problem isn't deadly.   You can  clear the locking  data by using the  "clear
  439. door" command: 
  440.  
  441.                              VARITALE /DOOR///D/ 
  442.  
  443. Not  only does this open the  door (if closed previously  with the CLOSE com-
  444. mand), but it will also reset all locking data.  This version of the  command
  445. can be executed  only at the  console or a local  workstation.  You  can skip
  446. this step,  but your users will  have to wait a  while for any  locks to time
  447. out. 
  448.  
  449. We regret any inconvenience that may be caused by our locking scheme.  It's a
  450. compromise  which  ensures that  VariTale will  run  on almost  any computer,
  451. network, DOS or multi-tasker. 
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458. 4
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471. The Unique File-locking Tag
  472.  
  473. VariTale performs  a lock  by writing a  locking record,  performing a  dummy
  474. write to  de-synchronize itself in certain environments,  then re-reading the
  475. record  to see  if it  has been altered.   If  it has,  it means  somebody is
  476. competing for the same resource.  In such a case, the lock is not acquired.
  477.  
  478. In order  to determine if a "collision"  has taken place (i.e.  more than one
  479. user is competing for the same resource), VariTale must have a unique item of
  480. data associated with each user.  This is absolutely essential.
  481.  
  482. VariTale compares port, user-name and system identification data.  
  483.  
  484.  
  485. Single-Processor Operation
  486.  
  487. If you  are running a single-processor  system (using a multi-tasker  such as
  488. Multi-Link,  Desqview, etc.) each  of your  users will  have a  different COM
  489. port.  In this case,  you need only pass the port address to  VariTale on the
  490. start-up line (e.g. VARITALE /DOOR/name/time/port).  This information is used
  491. both for file locking and setting up communications.
  492.  
  493.  
  494. LAN Operation
  495.  
  496. If you are using a LAN, all of your users may have the same port address.  In
  497. this case, the "port" parameter should  include an arbitrary system identifi-
  498. cation to permit file  locking.  Prefix the port address  with a letter (any-
  499. thing from ASCII decimal  65 to ASCII decimal 122  -- that is, A to  Z upper-
  500. case, some intervening special characters, and a to z lowercase) to provide a
  501. system identification to provide a unique locking tag.
  502.  
  503. Here's an example:
  504.  
  505. VARITALE /DOOR/JOE SMITH/45/X1016       <-- System "X", on COM1
  506.  
  507. Alternately, you may rely on the user-name as the unique tag if (and only if)
  508. you are certain that there will never  be two people with the same name using
  509. VariTale.  (That includes "System Operator", of course.)
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.                                                                             5
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.                                  MAINTENANCE
  538.  
  539.  
  540. Backups
  541.  
  542. Under  normal  circumstances, VariTale  should  be totally  self-maintaining.
  543. However, it is possible that a system crash could cause the index file (.TOC)
  544. to be corrupted.
  545.  
  546. To  deal with  this possibility,  VariTale comes  with a batch  program named
  547. BACK.  This copies the data files to a sub-directory of your VARITALE  direc-
  548. tory, named BACK.  To make your first backup, enter these commands:
  549.  
  550.      CD VARITALE              <-- Change to your VariTale directory
  551.      MD BACK                  <-- Create the safe-keeping directory
  552.      BACK                     <-- Make a backup
  553.  
  554. Should your files get messed up somehow, you can restore the last backup with
  555. the RESTORE command.
  556.  
  557. This technique  is by no means as good  as performing regular full-disk back-
  558. ups, but it is quick.   Please run BACK at least every few  days.  Your users
  559. will  be heart-broken  if their  masterpieces suddenly disappear  because you
  560. didn't have a recent backup.
  561.  
  562. NOTE:     We have  been told  by a  few VariTale installations  that the  TOC
  563.           files are, in fact,  quite vulnerable to damage  if they are  being
  564.           written to when a  system failure occurs.  To deal  with this prob-
  565.           lem,  we strongly recommend  that you always  have a  backup of the
  566.           .TOC files that is  around 5 days old.  On an active VariTale, this
  567.           should give you sufficient protection.
  568.  
  569.  
  570. Librarian Commands
  571.  
  572. The librarian commands  are enabled with the  ENABLE command.  This  will ask
  573. for  a password.   This  is initially set  to "bookworm",  but this  can (and
  574. should) be changed with the CONFIG program.
  575.  
  576. There are three special commands for the librarian:  BURN, CLOSE and RENAME.
  577.  
  578.  
  579. BURN
  580.  
  581. This command  removes a  book from  the list.   This also  deletes the  files
  582. associated with the  book.  If you  want to preserve them  for posterity, you
  583. should first copy  them to a floppy disk.  Each  book has two files (.TOC and
  584. .VTB).   Thus, to preserve book #1, you'd  copy VARIA.TOC and also VARIA.VTB.
  585. Book #2 uses VARIB.TOC and VARIB.VTB, and so on.
  586.  
  587.  
  588.  
  589.  
  590. 6
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603. VariTale comes with  two dreadful  sample stories  named "The  Secret of  the
  604. Broken Sword"  and "Space Terror!".  Feel  free to use them to  test the BURN
  605. command.
  606.  
  607.  
  608. CLOSE
  609.  
  610. This command prevents further  users from entering VariTale unless  they have
  611. the librarian's password.  If they  type it in correctly, the library is  re-
  612. opened.  It  can also be re-opened  by using the "D" option  explained in the
  613. "Multi-User Operation" section.
  614.  
  615. This command is only useful on a multi-user system, of course.  It allows you
  616. to keep people  out of the program while you are performing maintenance, such
  617. as the RESTORE described in the "Maintenance" section.
  618.  
  619.  
  620. PRUNE
  621.  
  622. This command is  used to delete a chapter.  You  might do this if the chapter
  623. is offensive either to your morals or literary taste.
  624.  
  625. PRUNE deletes only  a single chapter and the pointer from a previous chapter.
  626. It does not delete all the branches emanating from the chapter.  You may have
  627. to PRUNE many times if you're doing a major clean-up.
  628.  
  629. PRUNE does not compress the book file, either; it simply removes the pointers
  630. associated with  the chapter and  blanks out its title  so it won't  show up.
  631. You will gain no additional disk space by PRUNEing.
  632.  
  633.  
  634. RENAME
  635.  
  636. This command lets you  rename a book.  You  may wish to do this if  the story
  637. branches away from the premise implied by the  original title.  It can not be
  638. used to rename a chapter.
  639.  
  640.  
  641. Why Show the Commands?
  642.  
  643. You may  be curious why  the HELP command  shows the librarian's  commands in
  644. addition to the  usual commands.  No  doubt, some system operators  will feel
  645. that this is  private information and that  it's none of the  users' business
  646. what he can do.
  647.  
  648. On the other hand,  if the users know what commands  you have available, they
  649. might not bother you  with requests that you can't deal with,  such as "Can I
  650. move a chapter after another one?"   No, you can't, and any observant  person
  651. will probably figure this out -- which will save time for both of you.
  652.  
  653.  
  654.  
  655.  
  656.                                                                             7
  657.  
  658.  
  659.  
  660.  
  661.  
  662.